<!DOCTYPE html>
<html>
  <head>
    <meta charset='utf-8'>
    <meta http-equiv='X-UA-Compatible' content='chrome=1'>
    <meta name='viewport' content='width=device-width, initial-scale=1'>

    <meta name='twitter:card' content='summary'>
    <meta name='twitter:title' content='WebXR Samples Explainer'>
    <meta name='twitter:description' content='Overview of how the WebXR samples are designed'>

    <link rel='stylesheet' href='css/stylesheet.css'>
    <link rel='stylesheet' href='css/pygment_trac.css'>

    <style>
      h3 {
        font-size: 1.0em;
        margin-top: 2em;
      }

      .github-link {
        font-size: 0.8em;
      }
    </style>

    <!--[if lt IE 9]>
    <script src='https://html5shiv.googlecode.com/svn/trunk/html5.js'></script>
    <![endif]-->
    <title>WebXR - Samples Explainer</title>
  </head>
  <body>

    <div class='container' id='container'>
      <header class='header'>
        <div id='nav'>
            <a href='./index.html' class='selected'>Samples</a>
        </div>

        <h1><a href='' class='wordmark'><span>WebXR</span></a></h1>
        <h2 class='tagline'>Samples Explainer</h2>
      </header>

      <main class='main' id='main'>
        <h3>What are these?</h3>
        <p>These samples have been created to give developers a set of simple, fun, readable apps that demonstrate various aspects of using the WebXR API. They are designed to focus on API use rather than the details of how the WebGL rendering is done.</p>

        <h3>Who are they for?</h3>
        <p>The samples will be most useful as a reference for developers that want to use the WebXR API directly in their own project or add XR functionality to their libraries. They are also handy for testing the functionality of WebXR implementations.</p>

        <p>If you are using a graphics framework in your project you should check it's documentation first, as they may already have WebXR support built in! In that case, you should refer to the library documentation for details on how to use XR features.</p>

        <h3>How are they formatted</h3>
        <p>The samples are provided as web pages with heavily commented javscript code. Each page covers a single, targeted topic relating to API use. Code that has already been well commented in a previous sample will typically not be commented in subsequent samples in order to make it easier to focus on the newly introduced concepts, so if you see an uncommented code block that you don't understand check the previous samples and you will probably find the explanation that you're looking for.</p>

        <h3>What's the deal with WebGL?</h3>
        <p>Today the primary way of drawing XR content is via the <a href="https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API">WebGL API</a>. WebGL provides an efficient way of rendering 3D graphics in the browser, which is great for XR applications that require high performance.</p>

        <p>Unfortunately WebGL is fairly verbose and can be hard to follow for developers who aren't already familiar with it. Because of this, these samples generally avoid spending much time on the details of how the WebGL rendering is done. Otherwise they would quickly turn into WebGL tutorials with a little bit of XR on the side. Instead the focus is on how to get the necessary values from the WebXR API to feed into WebGL to ensure that the rendering is done correctly.</p>
        
        <h3>To Framework or not to Framework?</h3>
        <p>Most usage of WebGL today happens via frameworks that significantly simplify the creation of 3D scenes compared to using raw WebGL. Some of the more popular examples are <a href="https://threejs.org/">three.js</a>, <a href="https://www.babylonjs.com/">babylon.js</a>, and <a href="https://playcanvas.com/">PlayCanvas</a>. There's also frameworks that are specifically designed to create XR content on the web, such as <a href="https://aframe.io/">A-Frame</a> and <a href="https://facebook.github.io/react-vr/">ReactVR</a>. These are all <i>fantastic</i> libraries with their own strengths and focuses, and in general it's recommended that you find tools that suit your needs and rely on them rather than trying to build your own rendering systems from scratch.</p>

        <p>However, most frameworks will also hide away the details of interacting with the WebXR API. That's generally great for users, but not terribly useful when the entire point of your code is to demonstrate how to use the API! At the same time, we don't want the WebXR logic to be obscured by hundreds of lines of WebGL calls. As a result, these samples make use of their own <a href="https://github.com/immersive-web/webxr-samples/tree/master/js/cottontail">minimalistic rendering library</a> that is specifically designed to highlight use of the WebXR API and de-emphasize the WebGL rendering logic. It is <b>not</b> recommended that you use this library in your own projects, as you will almost certainly be better served by one of the more popular, better established frameworks.</p>
      </main>

      <footer class='footer'>
      </footer>
    </div>
  </body>
</html>
